home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 July / Chip Temmuz 2004.iso / program / antispam / RazorAgent_SDK / razor-agents-sdk-2.03.exe / Net-DNS-0.23 / lib / Net / DNS.pm
Encoding:
Perl POD Document  |  2002-06-12  |  14.3 KB  |  571 lines
  1. package Net::DNS;
  2. # $Id: DNS.pm,v 1.18 2002/06/11 22:31:16 ctriv Exp $
  3.  
  4. use strict;
  5. use vars qw(
  6.     $VERSION
  7.     $DNSSEC
  8.     @ISA
  9.     @EXPORT
  10.     %typesbyname
  11.     %typesbyval
  12.     %classesbyname
  13.     %classesbyval
  14.     %opcodesbyname
  15.     %opcodesbyval
  16.     %rcodesbyname
  17.     %rcodesbyval
  18. );
  19.  
  20. $VERSION = "0.23";
  21.  
  22. use Net::DNS::Resolver;
  23. use Net::DNS::Packet;
  24. use Net::DNS::Update;
  25. use Net::DNS::Header;
  26. use Net::DNS::Question;
  27. use Net::DNS::RR;
  28.  
  29.  
  30. BEGIN {
  31.     eval { require Net::DNS::RR::SIG };
  32.     # $@ will be true if any errors where encountered 
  33.     # loading SIG.pm
  34.     $DNSSEC = $@ ? 0 : 1;
  35. }
  36.  
  37.  
  38.  
  39.  
  40. require Exporter;
  41. @ISA = qw(Exporter);
  42. @EXPORT = qw(mx yxrrset nxrrset yxdomain nxdomain rr_add rr_del);
  43.  
  44. %typesbyname = (
  45.      "SIGZERO"   => 0,       # RFC2931 consider this a pseudo type
  46.     "A"            => 1,        # RFC 1035, Section 3.4.1
  47.     "NS"        => 2,        # RFC 1035, Section 3.3.11
  48.     "MD"        => 3,        # RFC 1035, Section 3.3.4 (obsolete)
  49.     "MF"        => 4,        # RFC 1035, Section 3.3.5 (obsolete)
  50.     "CNAME"        => 5,        # RFC 1035, Section 3.3.1
  51.     "SOA"        => 6,        # RFC 1035, Section 3.3.13
  52.     "MB"        => 7,        # RFC 1035, Section 3.3.3
  53.     "MG"        => 8,        # RFC 1035, Section 3.3.6
  54.     "MR"        => 9,        # RFC 1035, Section 3.3.8
  55.     "NULL"        => 10,        # RFC 1035, Section 3.3.10
  56.     "WKS"        => 11,        # RFC 1035, Section 3.4.2 (deprecated)
  57.     "PTR"        => 12,        # RFC 1035, Section 3.3.12
  58.     "HINFO"        => 13,        # RFC 1035, Section 3.3.2
  59.     "MINFO"     => 14,        # RFC 1035, Section 3.3.7
  60.     "MX"        => 15,        # RFC 1035, Section 3.3.9
  61.     "TXT"        => 16,        # RFC 1035, Section 3.3.14
  62.     "RP"        => 17,        # RFC 1183, Section 2.2
  63.     "AFSDB"        => 18,        # RFC 1183, Section 1
  64.     "X25"        => 19,        # RFC 1183, Section 3.1
  65.     "ISDN"        => 20,        # RFC 1183, Section 3.2
  66.     "RT"        => 21,        # RFC 1183, Section 3.3
  67.     "NSAP"        => 22,        # RFC 1706, Section 5
  68.     "NSAP_PTR"    => 23,        # RFC 1348 (obsolete)
  69.      "SIG"        => 24,        # RFC 2535, Section 4.1
  70.      "KEY"        => 25,        # RFC 2535, Section 3.1
  71.      "PX"        => 26,        # RFC 2163,
  72.     "GPOS"        => 27,        # RFC 1712 (obsolete)
  73.     "AAAA"        => 28,        # RFC 1886, Section 2.1
  74.     "LOC"        => 29,        # RFC 1876
  75.     "NXT"        => 30,        # RFC 2535, Section 5.2
  76.     "EID"        => 31,        # draft-ietf-nimrod-dns-xx.txt
  77.     "NIMLOC"    => 32,        # draft-ietf-nimrod-dns-xx.txt
  78.     "SRV"        => 33,        # RFC 2052
  79.     "ATMA"        => 34,        # ???
  80.     "NAPTR"        => 35,        # RFC 2168
  81.     "KX"        => 36,        # RFC 2230
  82.      "CERT"        => 37,        # RFC 2538
  83.     "OPT"       => 41,      # RFC 2671
  84.     "DS"        => 43,        # Not ASSIGNED YET...!!! draft
  85.     "UINFO"        => 100,        # non-standard
  86.     "UID"        => 101,        # non-standard
  87.     "GID"        => 102,        # non-standard
  88.     "UNSPEC"    => 103,        # non-standard
  89.     "TSIG"        => 250,        # RFC 2931
  90.     "IXFR"        => 251,        # RFC 1995
  91.     "AXFR"        => 252,        # RFC 1035
  92.     "MAILB"        => 253,        # RFC 1035 (MB, MG, MR)
  93.     "MAILA"        => 254,        # RFC 1035 (obsolete - see MX)
  94.     "ANY"        => 255,        # RFC 1035
  95. );
  96. %typesbyval = reverse %typesbyname;
  97.  
  98.  
  99. %classesbyname = (
  100.     "IN"        => 1,        # RFC 1035
  101.     "CH"        => 3,        # RFC 1035
  102.     "HS"        => 4,        # RFC 1035
  103.     "NONE"        => 254,        # RFC 2136
  104.     "ANY"        => 255,        # RFC 1035
  105. );
  106. %classesbyval = reverse %classesbyname;
  107.  
  108.  
  109. %opcodesbyname = (
  110.     "QUERY"        => 0,        # RFC 1035
  111.     "IQUERY"    => 1,        # RFC 1035
  112.     "STATUS"    => 2,        # RFC 1035
  113.     "NS_NOTIFY_OP"    => 4,        # RFC 1996
  114.     "UPDATE"    => 5,        # RFC 2136
  115. );
  116. %opcodesbyval = reverse %opcodesbyname;
  117.  
  118.  
  119. %rcodesbyname = (
  120.     "NOERROR"    => 0,        # RFC 1035
  121.     "FORMERR"    => 1,        # RFC 1035
  122.     "SERVFAIL"    => 2,        # RFC 1035
  123.     "NXDOMAIN"    => 3,        # RFC 1035
  124.     "NOTIMP"    => 4,        # RFC 1035
  125.     "REFUSED"    => 5,        # RFC 1035
  126.     "YXDOMAIN"    => 6,        # RFC 2136
  127.     "YXRRSET"    => 7,        # RFC 2136
  128.     "NXRRSET"    => 8,        # RFC 2136
  129.     "NOTAUTH"    => 9,        # RFC 2136
  130.     "NOTZONE"    => 10,        # RFC 2136
  131. );
  132. %rcodesbyval = reverse %rcodesbyname;
  133.  
  134.  
  135. sub version    { $VERSION; }
  136. sub PACKETSZ    { 512; }
  137. sub HFIXEDSZ    {  12; }
  138. sub QFIXEDSZ    {   4; }
  139. sub RRFIXEDSZ    {  10; }
  140. sub INT32SZ    {   4; }
  141. sub INT16SZ    {   2; }
  142.  
  143.  
  144.  
  145. # mx()
  146. #
  147. # Usage:
  148. #    my @mxes = mx('example.com', 'IN');
  149. #
  150. sub mx {
  151.     # If the first argument is a object, use that as our resolver.
  152.     my $res = ref $_[0] ? shift : Net::DNS::Resolver->new;
  153.  
  154.     # assign our arguments, setting class to 'IN' if not set for us.
  155.     my ($name, $class) = @_;
  156.     $class ||= 'IN';
  157.  
  158.     # We return failure unless we get an answer.
  159.     my $ans = $res->query($name, "MX", $class) || return;
  160.  
  161.     # This construct is best read backwords.
  162.     #
  163.     # First we take the answer secion of the packet.
  164.     # Then we take just the MX records from that list
  165.     # Then we sort the list by preference
  166.     # Then we return it.
  167.     # We do this into an array to force list context.
  168.     my @ret = sort { $a->preference <=> $b->preference } 
  169.                  grep { $_->type eq 'MX'} $ans->answer;
  170.  
  171.  
  172.     return @ret;
  173. }
  174.  
  175. sub yxrrset {
  176.     my $string = shift;
  177.     return Net::DNS::RR->new_from_string($string, "yxrrset");
  178. }
  179.  
  180. sub nxrrset {
  181.     my $string = shift;
  182.     return Net::DNS::RR->new_from_string($string, "nxrrset");
  183. }
  184.  
  185. sub yxdomain {
  186.     my $string = shift;
  187.     return Net::DNS::RR->new_from_string($string, "yxdomain");
  188. }
  189.  
  190. sub nxdomain {
  191.     my $string = shift;
  192.     return Net::DNS::RR->new_from_string($string, "nxdomain");
  193. }
  194.  
  195. sub rr_add {
  196.     my $string = shift;
  197.     return Net::DNS::RR->new_from_string($string, "rr_add");
  198. }
  199.  
  200. sub rr_del {
  201.     my $string = shift;
  202.     return Net::DNS::RR->new_from_string($string, "rr_del");
  203. }
  204.  
  205. 1;
  206. __END__
  207.  
  208. =head1 NAME
  209.  
  210. Net::DNS - Perl interface to the DNS resolver
  211.  
  212. =head1 SYNOPSIS
  213.  
  214. C<use Net::DNS;>
  215.  
  216. =head1 DESCRIPTION
  217.  
  218. Net::DNS is a collection of Perl modules that act as a Domain
  219. Name System (DNS) resolver.  It allows the programmer to perform
  220. DNS queries that are beyond the capabilities of C<gethostbyname>
  221. and C<gethostbyaddr>.
  222.  
  223. The programmer should be somewhat familiar with the format of
  224. a DNS packet and its various sections.  See RFC 1035 or
  225. I<DNS and BIND> (Albitz & Liu) for details.
  226.  
  227. =head2 Resolver Objects
  228.  
  229. A resolver object is an instance of the C<Net::DNS::Resolver> class.
  230. A program can have multiple resolver objects, each maintaining
  231. its own state information such as the nameservers to be queried, 
  232. whether recursion is desired, etc.
  233.  
  234. =head2 Packet Objects
  235.  
  236. C<Net::DNS::Resolver> queries return C<Net::DNS::Packet> objects.  Packet
  237. objects have five sections:
  238.  
  239. =over 3
  240.  
  241. =item *
  242.  
  243. The header section, a C<Net::DNS::Header> object.
  244.  
  245. =item *
  246.  
  247. The question section, a list of C<Net::DNS::Question> objects.
  248.  
  249. =item *
  250.  
  251. The answer section, a list of C<Net::DNS::RR> objects.
  252.  
  253. =item *
  254.  
  255. The authority section, a list of C<Net::DNS::RR> objects.
  256.  
  257. =item *
  258.  
  259. The additional section, a list of C<Net::DNS::RR> objects.
  260.  
  261. =back
  262.  
  263. The C<Net::DNS::Update> package is a front-end to C<Net::DNS::Packet>
  264. for creating packet objects to be used in dynamic updates.
  265.  
  266. =head2 Header Objects
  267.  
  268. C<Net::DNS::Header> objects represent the header section of a DNS packet.
  269.  
  270. =head2 Question Objects
  271.  
  272. C<Net::DNS::Question> objects represent the question section of a DNS packet.
  273.  
  274. =head2 RR Objects
  275.  
  276. C<Net::DNS::RR> is the base class for DNS resource record (RR) objects in
  277. the answer, authority, and additional sections of a DNS packet.
  278.  
  279. Don't assume that RR objects will be of the type you requested -- always
  280. check an RR object's type before calling any of its methods.
  281.  
  282. =head1 METHODS
  283.  
  284. See the manual pages listed above for other class-specific methods.
  285.  
  286. =head2 version
  287.  
  288.     print Net::DNS->version, "\n";
  289.  
  290. Returns the version of Net::DNS.
  291.  
  292. =head2 mx
  293.  
  294.     # Use a default resolver -- can't get an error string this way.
  295.     use Net::DNS;
  296.     my @mx = mx("example.com");
  297.  
  298.     # Use your own resolver object.
  299.     use Net::DNS;
  300.     my $res = Net::DNS::Resolver->new;
  301.     my  @mx = mx($res, "example.com");
  302.  
  303. Returns a list of C<Net::DNS::RR::MX> objects representing the MX
  304. records for the specified name; the list will be sorted by preference.
  305. Returns an empty list if the query failed or no MX records were
  306. found.
  307.  
  308. This method does not look up A records -- it only performs MX queries.
  309.  
  310. See L</EXAMPLES> for a more complete example.
  311.  
  312. =head2 yxrrset
  313.  
  314. Use this method to add an "RRset exists" prerequisite to a dynamic
  315. update packet.  There are two forms, value-independent and
  316. value-dependent:
  317.  
  318.     # RRset exists (value-independent)
  319.     $packet->push("pre", yxrrset("host.example.com A"));
  320.  
  321. Meaning:  At least one RR with the specified name and type must
  322. exist.
  323.  
  324.     # RRset exists (value-dependent)
  325.     $packet->push("pre", yxrrset("host.example.com A 10.1.2.3"));
  326.  
  327. Meaning:  At least one RR with the specified name and type must
  328. exist and must have matching data.
  329.  
  330. Returns a C<Net::DNS::RR> object or C<undef> if the object couldn't
  331. be created.
  332.  
  333. =head2 nxrrset
  334.  
  335. Use this method to add an "RRset does not exist" prerequisite to
  336. a dynamic update packet.
  337.  
  338.     $packet->push("pre", nxrrset("host.example.com A"));
  339.  
  340. Meaning:  No RRs with the specified name and type can exist.
  341.  
  342. Returns a C<Net::DNS::RR> object or C<undef> if the object couldn't
  343. be created.
  344.  
  345. =head2 yxdomain
  346.  
  347. Use this method to add a "name is in use" prerequisite to a dynamic
  348. update packet.
  349.  
  350.     $packet->push("pre", yxdomain("host.example.com"));
  351.  
  352. Meaning:  At least one RR with the specified name must exist.
  353.  
  354. Returns a C<Net::DNS::RR> object or C<undef> if the object couldn't
  355. be created.
  356.  
  357. =head2 nxdomain
  358.  
  359. Use this method to add a "name is not in use" prerequisite to a
  360. dynamic update packet.
  361.  
  362.     $packet->push("pre", nxdomain("host.example.com"));
  363.  
  364. Meaning:  No RR with the specified name can exist.
  365.  
  366. Returns a C<Net::DNS::RR> object or C<undef> if the object couldn't
  367. be created.
  368.  
  369. =head2 rr_add
  370.  
  371. Use this method to add RRs to a zone.
  372.  
  373.     $packet->push("update", rr_add("host.example.com A 10.1.2.3"));
  374.  
  375. Meaning:  Add this RR to the zone.
  376.  
  377. RR objects created by this method should be added to the "update"
  378. section of a dynamic update packet.  The TTL defaults to 86400
  379. seconds (24 hours) if not specified.
  380.  
  381. Returns a C<Net::DNS::RR> object or C<undef> if the object couldn't
  382. be created.
  383.  
  384. =head2 rr_del
  385.  
  386. Use this method to delete RRs from a zone.  There are three forms:
  387. delete an RRset, delete all RRsets, and delete an RR.
  388.  
  389.     # Delete an RRset.
  390.     $packet->push("update", rr_del("host.example.com A"));
  391.  
  392. Meaning:  Delete all RRs having the specified name and type.
  393.  
  394.     # Delete all RRsets.
  395.     $packet->push("update", rr_del("host.example.com"));
  396.  
  397. Meaning:  Delete all RRs having the specified name.
  398.  
  399.     # Delete an RR.
  400.     $packet->push("update", rr_del("host.example.com A 10.1.2.3"));
  401.  
  402. Meaning:  Delete all RRs having the specified name, type, and data.
  403.  
  404. RR objects created by this method should be added to the "update"
  405. section of a dynamic update packet.
  406.  
  407. Returns a C<Net::DNS::RR> object or C<undef> if the object couldn't
  408. be created.
  409.  
  410. =head1 EXAMPLES
  411.  
  412. The following examples show how to use the C<Net::DNS> modules.
  413. See the other manual pages and the demo scripts included with the
  414. source code for additional examples.
  415.  
  416. See the C<Net::DNS::Update> manual page for an example of performing
  417. dynamic updates.
  418.  
  419. =head2 Look up a host's addresses.
  420.  
  421.   use Net::DNS;
  422.   my $res   = Net::DNS::Resolver->new;
  423.   my $query = $res->search("host.example.com");
  424.   
  425.   if ($query) {
  426.       foreach my $rr ($query->answer) {
  427.           next unless $rr->type eq "A";
  428.           print $rr->address, "\n";
  429.       }
  430.   }
  431.   else {
  432.       print "query failed: ", $res->errorstring, "\n";
  433.   }
  434.  
  435. =head2 Find the nameservers for a domain.
  436.  
  437.   use Net::DNS;
  438.   my $res   = Net::DNS::Resolver->new;
  439.   my $query = $res->query("example.com", "NS");
  440.   
  441.   if ($query) {
  442.       foreach $rr ($query->answer) {
  443.           next unless $rr->type eq "NS";
  444.           print $rr->nsdname, "\n";
  445.       }
  446.   }
  447.   else {
  448.       print "query failed: ", $res->errorstring, "\n";
  449.   }
  450.  
  451. =head2 Find the MX records for a domain.
  452.  
  453.   use Net::DNS;
  454.   my $name = "example.com";
  455.   my $res  = Net::DNS::Resolver->new;
  456.   my @mx   = mx($res, $name);
  457.   
  458.   if (@mx) {
  459.       foreach $rr (@mx) {
  460.           print $rr->preference, " ", $rr->exchange, "\n";
  461.       }
  462.   }
  463.   else {
  464.       print "can't find MX records for $name: ", $res->errorstring, "\n";
  465.   }
  466.  
  467.  
  468. =head2 Print a domain's SOA record in zone file format.
  469.  
  470.   use Net::DNS;
  471.   my $res   = Net::DNS::Resolver->new;
  472.   my $query = $res->query("example.com", "SOA");
  473.   
  474.   if ($query) {
  475.       ($query->answer)[0]->print;
  476.   }
  477.   else {
  478.       print "query failed: ", $res->errorstring, "\n";
  479.   }
  480.  
  481. =head2 Perform a zone transfer and print all the records.
  482.  
  483.   use Net::DNS;
  484.   my $res  = Net::DNS::Resolver->new;
  485.   $res->nameservers("ns.example.com");
  486.   
  487.   my @zone = $res->axfr("example.com");
  488.   
  489.   foreach $rr (@zone) {
  490.       $rr->print;
  491.   }
  492.  
  493. =head2 Perform a background query and do some other work while waiting
  494. for the answer.
  495.  
  496.   use Net::DNS;
  497.   my $res    = Net::DNS::Resolver->new;
  498.   my $socket = $res->bgsend("host.example.com");
  499.  
  500.   until ($res->bgisready($socket)) {
  501.       # do some work here while waiting for the answer
  502.       # ...and some more here
  503.   }
  504.  
  505.   my $packet = $res->bgread($socket);
  506.   $packet->print;
  507.  
  508.  
  509. =head2 Send a background query and use select to determine when the answer
  510. has arrived.
  511.  
  512.   use Net::DNS;
  513.   use IO::Select;
  514.   
  515.   my $timeout = 5;
  516.   my $res     = Net::DNS::Resolver->new;
  517.   my $bgsock  = $res->bgsend("host.example.com");
  518.   my $sel     = IO::Select->new($bgsock);
  519.   
  520.   # Add more sockets to $sel if desired.
  521.   my @ready = $sel->can_read($timeout);
  522.   if (@ready) {
  523.       foreach my $sock (@ready) {
  524.           if ($sock == $bgsock) {
  525.               my $packet = $res->bgread($bgsock);
  526.               $packet->print;
  527.               $bgsock = undef;
  528.           }
  529.           # Check for the other sockets.
  530.           $sel->remove($sock);
  531.           $sock = undef;
  532.       }
  533.   }
  534.   else {
  535.       print "timed out after $timeout seconds\n";
  536.   }
  537.  
  538. =head1 BUGS
  539.  
  540. C<Net::DNS> is slow.  Real slow.
  541.  
  542. For other items to be fixed, please see the TODO file included with
  543. the source distribution.
  544.  
  545. =head1 COPYRIGHT
  546.  
  547. Copyright (c) 1997-2002 Michael Fuhr.  All rights reserved.  This program 
  548. is free software; you can redistribute it and/or modify it under the same 
  549. terms as Perl itself. 
  550.  
  551. =head1 AUTHOR INFORMATION
  552.  
  553. Net::DNS is currently maintained by a group, led by:
  554.     Chris Reinhardt
  555.     ctriv@net-dns.org
  556.  
  557. Net::DNS was created by:
  558.     Michael Fuhr
  559.     mike@fuhr.org
  560.  
  561. For more information see:
  562.     http://www.net-dns.org/
  563.  
  564. =head1 SEE ALSO
  565.  
  566. L<perl(1)>, L<Net::DNS::Resolver>, L<Net::DNS::Packet>, L<Net::DNS::Update>,
  567. L<Net::DNS::Header>, L<Net::DNS::Question>, L<Net::DNS::RR>, RFC 1035,
  568. I<DNS and BIND> by Paul Albitz & Cricket Liu
  569.  
  570. =cut
  571.